package com.example.graphmovieapp.service;

import com.example.graphmovieapp.domain.entity.Movie;
import com.example.graphmovieapp.domain.entity.Person;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.util.List;
import java.util.Optional;

/**
 * MovieService接口，提供电影相关的业务操作
 * 
 * @author GraphMovieApp
 * @version 1.0
 */
public interface MovieService {

    /**
     * 保存电影
     * 
     * @param movie 要保存的电影
     * @return 保存后的电影
     */
    Movie saveMovie(Movie movie);

    /**
     * 根据ID查找电影
     * 
     * @param id 电影ID
     * @return 匹配的电影，如果不存在则返回Optional.empty()
     */
    Optional<Movie> findMovieById(Long id);

    /**
     * 查找所有电影
     * 
     * @return 所有电影列表
     */
    List<Movie> findAllMovies();

    /**
     * 根据ID删除电影
     * 
     * @param id 电影ID
     */
    void deleteMovie(Long id);

    /**
     * 根据标题查找电影
     * 
     * @param title 电影标题
     * @return 匹配的电影，如果不存在则返回Optional.empty()
     */
    Optional<Movie> findMovieByTitle(String title);

    /**
     * 根据发行年份查找电影
     * 
     * @param released 发行年份
     * @return 匹配的电影列表
     */
    List<Movie> findMoviesByReleased(Integer released);

    /**
     * 根据标题模糊查询电影
     * 
     * @param title 标题关键字
     * @return 包含关键字的电影列表
     */
    List<Movie> findMoviesByTitleContaining(String title);

    /**
     * 根据标题模糊查询电影（支持分页）
     * 
     * @param title 标题关键字
     * @param pageable 分页参数
     * @return 分页的电影列表
     */
    Page<Movie> findMoviesByTitleContaining(String title, Pageable pageable);

    /**
     * 根据发行年份范围查找电影
     * 
     * @param start 起始年份
     * @param end 结束年份
     * @return 在指定年份范围内的电影列表
     */
    List<Movie> findMoviesByReleasedBetween(Integer start, Integer end);

    /**
     * 根据发行年份范围查找电影（支持分页）
     * 
     * @param start 起始年份
     * @param end 结束年份
     * @param pageable 分页参数
     * @return 分页的电影列表
     */
    Page<Movie> findMoviesByReleasedBetween(Integer start, Integer end, Pageable pageable);

    /**
     * 查找指定演员参演的电影数量
     * 
     * @param name 演员姓名
     * @return 该演员参演的电影数量
     */
    Long countMoviesActedByPerson(String name);

    /**
     * 查找指定导演执导的电影数量
     * 
     * @param name 导演姓名
     * @return 该导演执导的电影数量
     */
    Long countMoviesDirectedByPerson(String name);

    /**
     * 查找同时担任演员和导演的电影
     * 
     * @param name 人物姓名
     * @return 该人物既参演又执导的电影列表
     */
    List<Movie> findMoviesActedAndDirectedByPerson(String name);

    /**
     * 查找合作演员（参演同一电影的不同演员）
     * 
     * @param name 演员姓名
     * @return 与该演员合作过的其他演员列表
     */
    List<Person> findCoActors(String name);

    /**
     * 创建电影并添加演员和导演
     * 
     * @param movie 电影对象
     * @param actorNames 演员姓名列表
     * @param directorNames 导演姓名列表
     * @return 创建的电影
     */
    Movie createMovieWithActorsAndDirectors(Movie movie, List<String> actorNames, List<String> directorNames);
}